/**
 * @file CHACHA20_Driver.h
 * @brief ChaCha20加密算法驱动头文件
 * @details 该头文件定义了ChaCha20加密算法的接口、数据结构和常量
 */

#ifndef CHACHA20_DRIVER_H
#define CHACHA20_DRIVER_H

#include <stdint.h>

/**
 * @def CHACHA20_BLOCK_SIZE
 * @brief ChaCha20块大小（字节）
 */
#define CHACHA20_BLOCK_SIZE    64

/**
 * @def CHACHA20_KEY_SIZE
 * @brief ChaCha20密钥大小（字节）
 */
#define CHACHA20_KEY_SIZE      32

/**
 * @def CHACHA20_NONCE_SIZE
 * @brief ChaCha20随机数大小（字节）
 */
#define CHACHA20_NONCE_SIZE    12

/**
 * @def CHACHA20_ROUNDS
 * @brief ChaCha20加密轮数
 * @note ChaCha20标准为20轮（10次双轮操作）
 */
#define CHACHA20_ROUNDS        20

/**
 * @struct ChaCha20Context
 * @brief ChaCha20算法上下文结构体
 * @details 用于维护加密状态和密钥流信息
 */
typedef struct {
    uint32_t state[16];            ///< 16个32位字的状态矩阵
    uint8_t keystream[64];         ///< 64字节密钥流缓冲区
    uint8_t keystream_pos;         ///< 当前密钥流使用位置（0-63）
} ChaCha20Context;

/**
 * @var uninitialized
 * @brief 未初始化内存变量，用于熵源收集
 * @note volatile修饰确保编译器不优化此变量
 */
extern volatile uint32_t uninitialized;

/**
 * @var locknum
 * @brief 锁码存储缓冲区
 * @details 用于存储4位数字锁码
 */
extern uint8_t locknum[4];

/* 函数声明 */

/**
 * @brief 初始化ChaCha20加密上下文
 * @param[out] ctx ChaCha20上下文指针
 * @param[in] key 32字节加密密钥
 * @param[in] nonce 12字节随机数
 * @param[in] counter 32位计数器值
 * @return 无
 */
void chacha20_init(ChaCha20Context *ctx, const uint8_t *key, const uint8_t *nonce, uint32_t counter);

/**
 * @brief ChaCha20加密/解密函数
 * @param[in,out] ctx ChaCha20上下文指针
 * @param[in] input 输入数据指针
 * @param[out] output 输出数据指针
 * @param[in] length 数据长度
 * @return 无
 * @note 加密和解密使用相同函数，因为ChaCha20是对称流密码
 */
void chacha20_crypt(ChaCha20Context *ctx, const uint8_t *input, uint8_t *output, uint32_t length);

/**
 * @brief 获取随机锁码
 * @return 无
 * @note 基于当前时间生成4位随机数字锁码
 */
void Get_LockNum(void);

/**
 * @brief 解锁验证函数
 * @param[in] dec 输入的十进制数字
 * @param[in] plaintext 明文数据
 * @return 验证结果：0=成功，非0=失败
 */
uint8_t UnLock(const uint8_t* dec, const uint8_t* plaintext);

/**
 * @brief 令牌解密测试函数
 * @param[in] given_token 输入的令牌数据
 * @return 解密结果：0=成功，1=失败
 * @note 用于验证令牌有效性并更新菜单余额
 */
uint8_t test_decrypt_given_token(const uint8_t* given_token);

#endif /* CHACHA20_DRIVER_H */